release: 1.0.0 — spec reconciliation, docs, and the first published release - #24

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 7-9: Define stack facts consistently: update AGENTS.md (lines
7-9), llms.txt (lines 3-5), and packages/entity/CLAUDE.md (lines 12-15) so
Postgres + Drizzle is scoped to generated applications, while preserving the
hand-written postgresDriver() and `@ultimat3/entity` driver distinctions. Also
align ArkType statements across llms.txt, README.md,
docs/architecture/01-package-map.md, and wiki/Error-Codes.md with
packages/schema/README.md: builtinT is the dependency-free default and ArkType
is only an optional configured provider.

In `@CHANGELOG.md`:
- Line 15: Define one consistent 1.0.0 bootstrap publishing path: update
CHANGELOG.md line 15 and PUBLISHING.md lines 43-45 to reconcile the OIDC claim
with the manual bootstrap requirements, and align the release workflow’s
bootstrap behavior accordingly. Ensure all documentation and the release process
describe the same prerequisite and publication sequence before OIDC trusted
publishing is used.

In `@docs/architecture/05-type-chain.md`:
- Around line 136-164: Align the environment migration across scaffolding,
discovery, and verification: make scaffolding generate the documented env.ts
using defineEnv, update app discovery so it no longer requires app.config.ts for
environment configuration, and add an environment-contract step to x verify.
Replace remaining environment-validation references to X_CONFIG_INVALID with
X_ENV_MISSING, while retaining X_CONFIG_INVALID only for app.config.ts schema
failures.

In `@docs/idea/02-primitives.md`:
- Around line 79-100: Update every entity() example in the named architecture
documents to pass the schema options as { columns, invariants } using the
shipped signature. In docs/idea/02-primitives.md, rename the invariant property
to invariants while preserving its existing constraint definitions.

In `@docs/idea/13-dx.md`:
- Line 180: Update the fenced code block containing the X_ENV_MISSING example in
docs/idea/13-dx.md to specify the text language, resolving the markdownlint
MD040 warning while preserving the example content.

In `@docs/idea/14-roadmap.md`:
- Line 22: Align the M6 status and sequencing language in the roadmap: either
change M6 from ✅ to 🚧 until the 50k-socket benchmark is measured, or explicitly
classify that benchmark as post-release validation and remove the claim that
realtime is gated on it. Apply the same consistency update to the corresponding
status entry.

In `@llms.txt`:
- Line 75: Update the planned x branch entry in llms.txt to describe
copy-on-write database branches, preview URLs, and scoped MCP sockets, matching
wiki/CLI-Reference.md. Preserve x db branch as the documented shipped
database-only command.

In `@packages/cli/src/cmd-verify.test.ts`:
- Around line 197-208: Update the finding fixture in the test “applies and
surfaces the host findings once one is registered” so Finding.fix is an exact,
executable instruction naming docs/idea/14-roadmap.md and the required status
marker, while preserving the existing assertions and finding code/cause.

In `@packages/cli/src/workspace-checks.ts`:
- Around line 72-79: Convert the exported ManifestFacts interface into an
exported type alias with the same readonly object properties and frameworkDeps
tuple shape, preserving its public structure while complying with the type-only
export rule.
- Around line 131-137: The frameworkDepsOf function currently reads only
dependencies; update it to collect string-valued `@ultimat3/`* pins from
dependencies, peerDependencies, and optionalDependencies while continuing to
exclude devDependencies. Add stale peerDependencies and optionalDependencies
fixtures in packages/cli/src/workspace-checks.test.ts:198-212 to verify
X_RELEASE_VERSION_SKEW detects them; the workspace-checks.ts anchor requires the
implementation change, and the test sibling requires fixture updates.

In `@packages/schema/README.md`:
- Around line 74-77: Align the top-level schema-provider claims with the
dependency-free builtin provider, identified by vendor 'ultimate', rather than
ArkType. Update README.md lines 142 and llms.txt lines 3-5 to match the
already-correct packages/schema/README.md content; no direct change is needed at
packages/schema/README.md lines 74-77.

In `@scripts/roadmap.ts`:
- Around line 1-8: Implement the advertised CLI entry point in
scripts/roadmap.ts: parse --json, invoke checkRoadmap, and render findings as
JSON when requested while preserving a human-readable default output. Ensure CLI
errors also honor --json, and make the direct bun run command execute the check.
- Around line 40-145: Replace the duplicated milestone facts in MILESTONES with
a single machine-readable roadmap source shared by the gate and docs generation
or validation. Update the roadmap workflow around MILESTONES so milestone
titles, statuses, and required artifacts are derived from that source, and
ensure docs/idea/14-roadmap.md is generated or validated against it rather than
maintained independently.
- Around line 9-10: Replace the node:fs and node:path imports in
scripts/roadmap.ts with equivalent Bun APIs for the existing file-existence and
path-joining operations; only retain the Node imports if the implementation
documents a specific unavoidable reason Bun cannot perform them.
- Around line 168-181: Update checkRoadmap so a missing ROADMAP_FILE produces a
documented X_* finding with an executable remediation instead of returning an
empty array. Add or reuse the appropriate finding helper near
missingStatusFinding and unverifiedFinding, and preserve the existing roadmap
validation flow when the file exists.
- Around line 151-165: The fix values returned by missingStatusFinding and
unverifiedFinding must be executable commands rather than prose. Replace each
message with a runnable fixer command that performs the required roadmap update
or restoration, and assign any newly introduced fixer behavior a stable,
documented error code consistent with the existing error-code conventions.

In `@scripts/verify.test.ts`:
- Around line 64-92: Move the direct checkRoadmap tests, including the “shipped
with missing artifact” and “missing status marker” cases, from verify.test.ts
into scripts/roadmap.test.ts beside roadmap.ts. Keep only the HOST_CHECKS
integration assertion in verify.test.ts, preserving the existing test behavior
and cleanup.

In `@site/lib/config.ts`:
- Around line 20-24: Update the FRAMEWORK_VERSION initialization in
site/lib/config.ts to parse the core package manifest as unknown, validate that
version is a valid semver string, and map malformed or invalid manifests to an
UltimateError with a stable X_* code, the original cause, and an executable fix:
instruction. Keep site/build.ts unchanged and ensure only validated version
strings are exported.

In `@site/pages/ai-first.md`:
- Around line 115-122: Update the documentation around the x db branch example
to remove the claim that its branch build ID scopes service-worker caches.
Associate cache isolation with the planned full x branch preview flow, while
preserving the explanation that x db branch currently provides a copy-on-write
database and preview URL.

In `@site/pages/deploy.md`:
- Around line 148-149: Update the ISR deployment description near the statement
that the framework emits plain files so it no longer implies the framework
pushes pages directly to a CDN; clarify that CDN uploads are performed by
external tooling, or remove the conflicting table claim.

In `@site/pages/jobs.md`:
- Around line 117-119: Update the jobs documentation around the redis/nats
behavior to show the executable fix command `x jobs drain --to memory --json`,
then document the driver configuration change separately. In the CLI behavior
section, state that `X_NOT_IMPLEMENTED` appears in `findings` and the command
exits non-zero without propagating the error.

In `@site/pages/quickstart.md`:
- Line 98: Update the quickstart command example by removing the leading "$"
prompt marker from the x mcp serve line, since no command output is shown.
- Line 98: Update the quickstart example around the x mcp serve command to show
it only starts the CLI dev-tool catalog, then add a separate application request
invoking the registered postly.publishPost tool through tools/call. Remove the
`$` prompt from all commands in this example to satisfy MD014.

In `@site/pages/roadmap.md`:
- Around line 54-55: Update the roadmap’s M6 benchmark status in both the
release summary and the kill-criterion section to explicitly state that the
unmet gate was waived for the 1.0.0 release. Record the replacement condition or
follow-up requirement, and remove any wording that marks the criterion resolved
while the benchmark remains unrun.

In `@site/templates/home.html`:
- Line 12: Update site/build.ts to pass FRAMEWORK_VERSION into every template
fill map, then replace the hardcoded version text in site/templates/home.html:12
and site/templates/layout.html:52 and :142 with the template placeholder for
that value. Preserve the existing template rendering and JSON-LD behavior while
sourcing all displayed versions from the single FRAMEWORK_VERSION configuration
symbol.

In `@wiki/Configuration.md`:
- Around line 7-14: Update the configuration example to use the shipped
AppConfigInput shape: remove unsupported url and db fields from defineConfig,
and set pwa.offline to a supported strategy string instead of an object with
fallback. Keep the module-scope defineEnv call and its existing environment
declarations unchanged.

In `@wiki/Contributing.md`:
- Line 183: Generate the 17-step verification list from the single verification
registry and project it consistently into wiki/Contributing.md:183-183,
wiki/FAQ.md:73-73, wiki/Getting-Started.md:37, and
wiki/Entities-And-Migrations.md:133; remove stale check descriptions and update
each documentation copy whenever the registry changes.

In `@wiki/Deployment.md`:
- Line 5: Update wiki/Deployment.md line 5 to replace the single `x build
--target docker|binary|static` notation with three verbatim runnable commands or
prose outside the code span. Update wiki/FAQ.md line 16 to remove escaped pipes
and show the same three runnable commands; ensure neither document presents
pipes as shell arguments or pipelines.

In `@wiki/FAQ.md`:
- Around line 9-25: Reconcile the release-status statements with the milestone
status in docs/idea/14-roadmap.md, keeping the reconnect benchmark explicitly
marked unmeasured. Update wiki/FAQ.md lines 9-25 and 101-105 to use the
roadmap’s correct milestone number and shipped/open status, and update
wiki/Getting-Started.md line 157 to match; ensure all three sites consistently
describe the benchmark and shipped milestones.

In `@wiki/Home.md`:
- Line 5: Replace the hardcoded release-status values in the Home documentation
with values sourced from one shared release metadata definition, including
version, date, package count, and milestone status. Update the documentation
build or x verify flow to inject or validate those values across Home.md,
FAQ.md, Getting-Started.md, Deployment.md, Caching-And-Invalidation.md,
Configuration.md, Contributing.md, and Entities-And-Migrations.md, preventing
duplicated facts from drifting.

In `@wiki/Installation.md`:
- Around line 57-66: Update the environment configuration example to use the
shipped app.config.ts pattern, placing the defineEnv call there so loadApp()
discovers and validates it during boot. Alternatively, include the explicit
import and boot invocation, but do not leave defineEnv only in a root env.ts
file without an application call site.

In `@wiki/Jobs-And-Workflows.md`:
- Line 5: Reconcile the stable API documentation in Jobs-And-Workflows with the
deferred Redis and NATS driver status: update the driver rows and the `x jobs
drain --to redis` command to indicate they are planned, or remove them from the
shipped API section. Use the existing single source of truth for driver
availability and project the generated status into this documentation so it
cannot drift from the changelog.

In `@wiki/MCP-And-AI.md`:
- Line 25: Update the tool table in wiki/MCP-And-AI.md to use the shipped names
declared in the “Shipped names” section: actions.describe, manifest.read,
jobs.inspect, queue.depth, and verify.run. Remove outdated entries such as
actions.list, manifest.get, and tests.run, and ensure the table does not
advertise aliases or omit any shipped tool.

In `@wiki/Realtime.md`:
- Line 5: Update the duplicate reconnect benchmark status date in the Realtime
documentation from 2026-07 to 2026-08 so it matches the version status date, or
define the shared status date once and reuse it in both locations.

In `@wiki/Testing.md`:
- Line 160: Update the new fenced block in Testing.md that shows x verify output
to specify text as its language identifier, resolving the markdownlint MD040
violation while preserving the output content.

In `@wiki/The-Eight-Primitives.md`:
- Around line 18-25: Update the testing-related wording in The-Eight-Primitives
documentation to reflect that x g is registered and resource and policy are
shipped generators, without implying separate command files are required.
Replace the “failing test scaffolds” description so it states that generated
tests are intended to pass on the first run.
- Line 3: Update the generator description in “The-Eight-Primitives.md” to state
that x g resource emits passing test scaffolds, and remove “one of each” or
replace it with an accurate list excluding mutator and task, matching
resourceFiles().

In `@wiki/Upgrading.md`:
- Line 33: Update the migration documentation in Upgrading.md so Redis/NATS
job-driver migration is explicitly v2-only and is not presented as an available
1.0.0 procedure. Revise the later “all three drivers”, “x jobs drain --to
redis”, and jobs.driver-to-Redis guidance to remove unsupported 1.0.0 steps or
clearly scope them to v2, while retaining migration instructions only for
supported drivers.